Quick Start

Get up and running with ORB-SLAM3 in minutes

Overview

This guide will help you run your first ORB-SLAM3 example. We’ll use the monocular SLAM example with the TUM RGB-D dataset, which is one of the simplest configurations to get started.

Before proceeding, make sure you have installed ORB-SLAM3 and verified that the compilation was successful.

Quick Start with TUM Dataset

1. Download a Dataset

   Download a sample sequence from the TUM RGB-D dataset:

   # Create a directory for datasets
   mkdir -p ~/Datasets
   cd ~/Datasets
   
   # Download a small sequence (freiburg1_xyz, ~154 MB)
   wget https://vision.in.tum.de/rgbd/dataset/freiburg1/rgbd_dataset_freiburg1_xyz.tgz
   
   # Extract the dataset
   tar -xvzf rgbd_dataset_freiburg1_xyz.tgz
   

   This sequence contains 798 frames of a camera moving in x, y, and z directions.

2. Navigate to ORB-SLAM3 Directory

   Make sure you’re in the ORB-SLAM3 root directory:

   cd ~/ORB_SLAM3
   
3. Run Monocular SLAM

   Execute the monocular SLAM example:

   ./Examples/Monocular/mono_tum \
       Vocabulary/ORBvoc.txt \
       Examples/Monocular/TUM1.yaml \
       ~/Datasets/rgbd_dataset_freiburg1_xyz
   

   Command breakdown:

   • Vocabulary/ORBvoc.txt: The ORB vocabulary for place recognition
   • Examples/Monocular/TUM1.yaml: Camera calibration and SLAM parameters
   • ~/Datasets/rgbd_dataset_freiburg1_xyz: Path to the dataset
4. View the Results

   You should see two windows:

   1. ORB-SLAM3 Viewer: 3D visualization showing:
      • Green points: Current map points
      • Red boxes: Keyframes
      • Blue line: Current camera pose
      • Camera trajectory in real-time
   2. Frame Viewer: Shows the current frame with:
      • Tracked ORB features
      • Current tracking state
      • Number of tracked features

   The system needs a few frames to initialize. Look for the message “System initialized” in the terminal.

Understanding the Output

During execution, ORB-SLAM3 will print status information:

Images in the sequence: 798
-------
Start processing sequence ...

New Map created with 135 points
System initialized

Local Mapping: Active
Loop Closing: Active

After processing completes, you’ll see performance statistics:

-------
median tracking time: 0.0342
mean tracking time: 0.0389

The camera trajectory is automatically saved to KeyFrameTrajectory.txt in TUM format.

Understanding the System API

Here’s how the monocular example initializes and uses ORB-SLAM3 (from Examples/Monocular/mono_tum.cc:50):

// Create SLAM system. It initializes all system threads and gets ready to process frames.
ORB_SLAM3::System SLAM(argv[1], argv[2], ORB_SLAM3::System::MONOCULAR, true);

// Main tracking loop
for(int ni=0; ni<nImages; ni++)
{
    // Read image from file
    cv::Mat im = cv::imread(image_path, cv::IMREAD_UNCHANGED);
    double timestamp = vTimestamps[ni];
    
    // Pass the image to the SLAM system
    SLAM.TrackMonocular(im, timestamp);
}

// Stop all threads
SLAM.Shutdown();

// Save camera trajectory
SLAM.SaveKeyFrameTrajectoryTUM("KeyFrameTrajectory.txt");

System Constructor

The System constructor (from include/System.h:105) takes:

System(const string &strVocFile,           // Path to vocabulary file
       const string &strSettingsFile,      // Path to settings YAML file  
       const eSensor sensor,               // Sensor type
       const bool bUseViewer = true,       // Enable/disable viewer
       const int initFr = 0,               // Initial frame number
       const string &strSequence = std::string())  // Sequence name

Sensor Types

Available sensor types (from include/System.h:87-94):

enum eSensor{
    MONOCULAR=0,
    STEREO=1,
    RGBD=2,
    IMU_MONOCULAR=3,
    IMU_STEREO=4,
    IMU_RGBD=5,
};

Tracking Methods

Depending on your sensor configuration, use the appropriate tracking method:

// Monocular (from include/System.h:121)
Sophus::SE3f TrackMonocular(const cv::Mat &im, 
                             const double &timestamp,
                             const vector<IMU::Point>& vImuMeas = vector<IMU::Point>());

// Stereo (from include/System.h:110)
Sophus::SE3f TrackStereo(const cv::Mat &imLeft, 
                         const cv::Mat &imRight, 
                         const double &timestamp,
                         const vector<IMU::Point>& vImuMeas = vector<IMU::Point>());

// RGB-D (from include/System.h:116)
Sophus::SE3f TrackRGBD(const cv::Mat &im, 
                       const cv::Mat &depthmap, 
                       const double &timestamp,
                       const vector<IMU::Point>& vImuMeas = vector<IMU::Point>());

All tracking methods return the camera pose as a Sophus::SE3f transformation (empty if tracking fails).

Other Examples

Stereo SLAM (EuRoC Dataset)

# Download EuRoC dataset sequence
wget http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/machine_hall/MH_01_easy/MH_01_easy.zip
unzip MH_01_easy.zip -d ~/Datasets/EuRoC/MH01

# Run stereo SLAM
./Examples/Stereo/stereo_euroc \
    Vocabulary/ORBvoc.txt \
    Examples/Stereo/EuRoC.yaml \
    ~/Datasets/EuRoC/MH01 \
    Examples/Stereo/EuRoC_TimeStamps/MH01.txt

RGB-D SLAM

# Using the same TUM dataset with depth
./Examples/RGB-D/rgbd_tum \
    Vocabulary/ORBvoc.txt \
    Examples/RGB-D/TUM1.yaml \
    ~/Datasets/rgbd_dataset_freiburg1_xyz \
    Examples/RGB-D/associations/fr1_xyz.txt

RGB-D examples require association files that pair RGB images with depth images. These are provided in Examples/RGB-D/associations/.

Using Your Own Camera

To use ORB-SLAM3 with your own camera:

1. Calibrate Your Camera

   Follow the instructions in Calibration_Tutorial.pdf to calibrate your camera and create a YAML configuration file.

2. Modify an Example

   Copy and modify one of the provided examples (e.g., Examples/Monocular/mono_tum.cc) to read from your camera source instead of files.

3. Build Your Example

   Add your example to CMakeLists.txt and rebuild:

   ./build.sh
   

For Intel RealSense cameras (T265, D435i), ready-to-use examples are provided in the Examples directory.

Performance Tips

Optimize for Real-Time Performance

• Use a powerful computer (Intel i7 or equivalent)
• Reduce image resolution if needed (configure in YAML file)
• Disable the viewer for maximum performance: set the 4th parameter to false in the System constructor
• Compile in Release mode (default in build.sh)

Improve Tracking Robustness

• Ensure good lighting conditions
• Avoid rapid camera movements during initialization
• Include visual texture in the scene (avoid blank walls)
• For IMU configurations, keep the camera-IMU synchronized

Debug Tracking Issues

• Check the Frame Viewer for the number of tracked features (should be > 30)
• Look for “Tracking Lost” messages in the terminal
• Verify camera calibration is correct
• Enable verbose output by setting the verbosity level

Saving and Loading Results

ORB-SLAM3 provides several methods to save trajectory data (from include/System.h:143-168):

// Save in TUM RGB-D format (works for all sensor types)
SLAM.SaveKeyFrameTrajectoryTUM("KeyFrameTrajectory.txt");

// Save in EuRoC format
SLAM.SaveTrajectoryEuRoC("CameraTrajectory.txt");
SLAM.SaveKeyFrameTrajectoryEuRoC("KeyFrameTrajectory.txt");

// Save in KITTI format (stereo and RGB-D only)
SLAM.SaveTrajectoryKITTI("CameraTrajectory.txt");

Always call SLAM.Shutdown() before saving trajectories to ensure all threads have finished processing.

Next Steps

Now that you’ve run your first example, explore more advanced features:

API Reference

Learn about the complete System class API

Configuration

Understand the YAML configuration files

Examples

Explore examples for all sensor configurations

Datasets

Download and use popular SLAM datasets